.\" libxbee - a C library to aid the use of Digi's XBee wireless modules
.\"           running in API mode.
.\" 
.\" Copyright (C) 2009 onwards  Attie Grande (attie@attie.co.uk)
.\" 
.\" libxbee is free software: you can redistribute it and/or modify it
.\" under the terms of the GNU Lesser General Public License as published by
.\" the Free Software Foundation, either version 3 of the License, or
.\" (at your option) any later version.
.\" 
.\" libxbee is distributed in the hope that it will be useful,
.\" but WITHOUT ANY WARRANTY; without even the implied warranty of
.\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
.\" GNU Lesser General Public License for more details.
.\" 
.\" You should have received a copy of the GNU Lesser General Public License
.\" along with this program. If not, see <http://www.gnu.org/licenses/>.
.TH XBEE_CONRX 3  04-Mar-2012 "GNU" "Linux Programmer's Manual"
.SH NAME
xbee_conRx
.SH SYNOPSIS
.B #include <xbee.h>
.sp
.BI "xbee_err xbee_conRx(struct xbee_con *" con ", struct xbee_pkt **" retPkt ", int *" remainingPackets ");"
.sp
.BI "xbee_err xbee_conRxWait(struct xbee_con *" con ", struct xbee_pkt **" retPkt ", int *" remainingPackets ");"
.SH DESCRIPTION
.BR xbee_conRx ()
allows you to retrieve information from an active connection.
.I con
must be non-NULL, and must point at a valid connection. At least one of
.IR retPkt " and " remainingPackets
must be non-NULL.
.sp
.I retPkt
may optionally be non-NULL, in which case the next packet in the connection's buffer is returned to you.
If you receive a packet from a connection, you must not forget to call
.BR xbee_pktFree (3)
when you are finished with it.
If
.I retPkt
is non-NULL, and a callback has been configured for the connection, then
.B XBEE_EINVAL
will be returned and neither
.IR retPkt " or " remainingPackets
will have been updated - see
.BR xbee_conCallbackSet (3)
for more information.
.sp
.I remainingPackets
may also optionally be non-NULL. If it is non-NULL, then it will be populated with the number of packets that are currently in the connection's buffer.
.sp
When a callback is enabled,
.BR xbee_conRx ()
may be called with
.I retPkt
set to NULL, and
.I remainingPackets
set as non-NULL.
.sp
.BR xbee_conRxWait ()
is identical to
.BR xbee_conRx (),
except that it will busy-wait for upto 1 second, checking if there is a packet available.
.SS Return Value
On success this function will return XBEE_ENONE, otherwise an error number from
.IR "enum xbee_errors" " (as specified in " <xbee.h> ).
.sp
XBEE_ENOTEXISTS will be returned if there is no packet available to retrieved.
.SH EXAMPLE
.in +4n
.nf
#include <xbee.h>

struct xbee *xbee;
struct xbee_con *con;
struct xbee_pkt *pkt;

/* initialize xbee, using xbee_setup() */

/* initialize con, using xbee_conNew() */

/* receive some data for con */

if (xbee_conRx(con, &pkt, NULL) != XBEE_ENONE) return;

/* use pkt */

if (xbee_pktFree(pkt) != XBEE_ENONE) return;
.fi
.in
.SH AUTHOR
Attie Grande <attie@attie.co.uk> 
.SH "SEE ALSO"
.BR libxbee (3)
.BR xbee_setup (3),
.BR xbee_conNew (3),
.BR xbee_pktFree (3),
.BR xbee_conCallbackSet (3)
